Review: Onchain Calls

Must fix

• CallErrorExt unused import in "Basic call" example: The basic call example imports CallErrorExt but only uses .expect() (a standard Result method). CallErrorExt is only needed in the error handling example where .is_clean_reject() is called. Remove CallErrorExt from the basic call import.

• Import path: ic_cdk_macros::update vs ic_cdk::update: The examples import use ic_cdk_macros::update; but ic-cdk re-exports macros at the top level. The conventional import is use ic_cdk::update; (the multi-canister icskill uses use ic_cdk::{update, query};). Use the re-export for consistency with the rest of the docs. Applies to all Rust code blocks.

• Content brief gap — canister discovery: The stub brief explicitly asks for "canister discovery (env vars, ic_env cookie)" but this isn't covered. At minimum, add a short section or paragraph explaining how a canister learns the Principal of the canister it wants to call (hardcoded, init arg, environment). If better suited for a separate page, mention it and link to a stub.

Suggestions

• Content brief gap — calling third-party canisters: The brief mentions this. The bounded-wait section partially covers it ("canisters you do not control"), but it could be made more explicit with a paragraph about trust considerations when calling canisters outside your control (bounded wait + idempotency + checking outcomes).

• Content brief gap — pub/sub pattern: Mentioned in the brief and source material examples. Could reasonably be deferred to a separate page. If omitted, note it in the PR description so it's tracked.

• Bounded wait timeout example: .change_timeout(1) uses a 1-second timeout, which is very aggressive. Consider a more realistic value (e.g., 5 or 10) or add a comment explaining the unit and reasonable range.

• "Caller identity across await" Rust example: The example shows let caller = ic_cdk::api::msg_caller(); but doesn't actually use caller after the await — it ends with Ok(()). A more instructive example would show caller being used after an await point.

Verified

• All 5 internal links resolve to existing files (../../concepts/canisters.md, ../backends/certified-variables.md, parallel-calls.md, candid.md, ../security/inter-canister-calls.md)
• Rust CDK API verified against .sources/cdk-rs/ic-cdk/src/call.rs: Call::unbounded_wait, Call::bounded_wait, .with_arg(), .candid::<T>(), .candid_tuple(), CallErrorExt::is_clean_reject(), .change_timeout() all exist
• Motoko syntax verified against .sources/motoko/ and .sources/motoko-core/: persistent actor, import X "canister:name", mo:core/Error with Error.message(), mo:core/Result with Result.Result<Ok, Err>
• Technical claims cross-checked against multi-canister icskill: 2 MB payload limit, same-subnet single-round latency, cross-subnet 2-3 rounds, clean/non-clean reject semantics, unbounded wait upgrade risk — all accurate
• No dfx references, no .mdx/JSX, plain markdown only
• Frontmatter complete and consistent
• Page follows Diataxis "how-to guide" format correctly
• Upstream attribution comment present

Feedback addressed:

• Removed unused CallErrorExt import from basic call example
• Changed ic_cdk_macros::update → ic_cdk::update re-export across all Rust examples
• Added "Canister discovery" section covering Motoko compile-time import, Rust init argument, and hardcoded principals
• Added "Pub/sub pattern" section with Motoko publisher/subscriber examples (adapted from dfinity/examples/motoko/pub-sub). Added TODO comment for creating a Rust pub/sub example upstream.
• Added third-party canister calling guidance (bounded wait + idempotency + outcome querying)
• Changed .change_timeout(1) → .change_timeout(5) with unit comment
• Made caller identity example instructive — now shows caller used after an await point
• Pub/sub pattern deferred to separate page: no, included inline as a section (natural fit for inter-canister calls guide). Noted in PR description.

Feedback addressed (follow-up):

• Rewrote canister discovery section to recommend icp-cli's automatic PUBLIC_CANISTER_ID:<name> environment variables as the primary approach (informed by icp-cli/docs/concepts/canister-discovery.md)
• Added Rust (ic_cdk::api::env_var_value) and Motoko (Prim.envVar) code examples for reading env vars
• Moved init arguments and hardcoded principals to "Alternative approaches" subsection
• Added notes throughout about Motoko canister:name syntax being redesigned for icp-cli compatibility
• Added note on pub/sub subscriber's canister:pub import pointing to the canister discovery section